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TPU$FILE_SEARCH 

The TPU$FILE_SEARCH routine provides a simplified interface to the $SEARCH system service. 
DECTPU call this routine when TPU code executes the FILE_SEARCH built-in procedure. 



Format 

TPU$FILE_SEARCH result-string ,flags ,filespec ,default-spec ,related-spec 
RETURNS 



OpenVMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. Most utility routines return a condition value in RO. See Condition Values 
Returned. 



Arguments 
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OpenVMS usage: charstring 
type: character string 

access: write only 

mechanism: by descriptor 

Includes the components of the file specification passed by the flags argument. The memory for the return 
string is allocated via the Run-Time Library routine LIB$SGET1_DD. To deallocate memory for the 
string, use the Run-Time Library routine LIB$SFREE1_DD. 

flags 

OpenVMS usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 



Determines what file specification components should be returned. The following table lists the valid flag 
values: 



Flag 1 


Function 


TPU$M NODE 


Returns the node component of the file specification. 


TPU$M_DEV 


Returns the device component of the file specification. 


TPU$M_DIR 


Returns the directory component of the file specification. 


TPU$M_NAME 


Returns the name component of the file specification. 


TPU$M_TYPE 


Returns the type component of the file specification. 


TPU$M_VER 


Returns the version component of the file specification. 


TPU$M_REPARSE 


Reparses the file specification before processing. This is intended to be used to 
reset the file search. 


TPU$M_HEAD 


Returns NODE, DEVICE, and DIRECTORY components of the file specification. 
If the TPU$M NODE, TPU$M DEV or TPU$M DIR bits are set while 
TPU$M_HEAD is set, the routine will signal the error TPU$_INCKWDCOM and 
return. 


TPU$M_TAIL 


Returns NAME, TYPE and VERSION components of the file specification. If the 
TPU$M NAME, TPU$M TYPE or TPUSM VER bits are set while 
TPU$M_TAIL is set, the routine will signal the error TPU$_INCKWDCOM and 
return. 



TPUSM... indicates a mask. There is a corresponding value for each mask in the form TPU$V.„. 



filespec 
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OpenVMS usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Object file specification. 

default-spec 

OpenVMS usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

The default file specification. The default file specification fields are used to fill in the result-string when fields are 
omitted in the filespec argument. Use the related-spec argument to specify other substitutions. 

Use the value 0 when no default-spec is to be applied to the file specification. 

related-spec 

OpenVMS usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Contains the related file specification. The fields in the related file specification are used in the result-string for fields 
omitted in the filespec and default-spec arguments. 

Use the value 0 when no default-spec is to be applied to the file specification. 



Description 

This routine allows an application to verify the existence of, and return components of, a file specification. 
Wildcard operations are permitted. The routine uses the SPARSE and SSEARCH system services to seek 
the file specification. 

If no wildcards are included in the file specification string and the result-string returns a zero (0) length 
string, no file was found. If wildcard characters were present in the file specification and the result-string 
returns a zero (0) length string, there are no more files that match the wildcards. 

To find all the files that match a wildcard specification, repeatedly call this routine, passing the same 
arguments, until the routine returns a zero-length result string. 

The TPU$FILE_SEARCH routine is called by DECTPU when the TPU built-in procedure 
FILESEARCH is executed from TPU code. The return value of the built-in procedure is the string 
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Condition Values Returned 



TPU$_SUCCESS 


Normal successful completion. If the return string contains a null string, the final 
match operation was detected. 


TPU$_INCKWDCOM 


The flags argument had an illegal combination of values. 


TPU$_PARSEFAIL 


The requested repeat parse failed. 


TPU$ SEARCHFAIL 


An error occurred during the search operation. 



TPUSHANDLER 

The TPUSHANDLER routine is the DECTPU condition handler. 

The DECTPU condition handler invokes the SPUTMSG system service, passing it the address of 
TPU$MESSAGE. 



Format 

TPUSHANDLER signal_vector ,mechanism_vector 



RETURNS 

OpenVMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. Most utility routines return a condition value in RO. See Condition Values 
Returned. 



Arguments 

signalvector 

OpenVMS usage: argjist 

type: longword (unsigned) 
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access: modify 
mechanism: by reference 

Signal vector. See the OpenVMS System Services Reference Manual for information about the signal 
vector passed to a condition handler. 

mechanism_vector 

OpenVMS usage: arg^list 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mechanism vector. See the OpenVMS System Services Reference Manual for information about the 
mechanism vector passed to a condition handler. 



Description 

The TPU$MESSAGE routine performs the actual output of the message. The $PUTMSG system service 
only formats the message. It gets the settings for the message flags and facility name from the variables 
described in Section 8.1.2 . Those values can be modified only by the DECTPU built-in procedure SET. 

If the condition value received by the handler has a FATAL status or does not have the DECTPU facility 
code, the condition is resignaled. 

If the condition is TPU$_QUITTING, TPU$_EXITING, or TPU$_RECOVERFAIL, a request to 
UNWIND is made to the establisher of the condition handler. 

After handling the message, the condition handler returns with a continue status. DECTPU error message 
requests are made by signaling a condition to indicate which message should be written out. The 
arguments in the signal array are a correctly formatted message argument vector. This vector sometimes 
contains multiple conditions and formatted ASCII output (FAO) arguments for the associated messages. 
For example, if the editor attempts to open a file that does not exist, the DECTPU message 
TPU$_NOFILEACCESS is signaled. The FAO argument to this message is a string for the name of the 
file. This condition has an error status, followed by the OpenVMS RMS status field (STS) and status value 
field (STV). Because this condition does not have a fatal severity, the editor continues after handling the 
error. 

The editor does not automatically return from TPU$CONTROL. If you call the TPUSCONTROL routine, 
you must explicitly establish a way to regain control (for example, using the built-in procedure 
CALLJJSER). If you establish your own condition handler but call the DECTPU handler for certain 
conditions, the default condition handler must be established at the point in your program where you want 
to return control. You can also interrupt TPUSCONTROL by having your program specify and then trigger 
an asynchronous routine via the TPU$SPECIFY_ASNYC_ACTION and 
TPU$TRIGGER_ASYNC_ACTION routines. 

See the OpenVMS Calling Standard for details on writing a condition handler. 
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The TPU$INITIALIZE routine initializes DECTPU for text processing. This routine allocates global data 
structures, initializes global variables, and calls the appropriate setup routines for each of the major 
components of the editor, including the Screen Manager and the I/O subsystem. 



Format 

TPUSINITIALIZE callback [,user_arg] 



RETURNS 

OpenVMS usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Longword condition value. Most utility routines return a condition value in RO. Condition values that this 
routine can return are listed under Condition Values Returned. 



Argument 
callback 

OpenVMS usage: vector_longword_unsigned 
type: bound procedure value 

access: read only 

mechanism: by descriptor 

Callback routine. The callback argument is the address of a user- written routine that returns the address of 
an item list containing initialization parameters or a routine for handling file I/O operations. This callback 
routine must call a command line parsing routine, which can be TPU$CLIPARSE or a user-written parsing 
routine. 

Callable DECTPU defines item codes that you can use to specify initialization parameters. The following 
rules must be followed when building the item list: 

• If you use the TPU$_OTHER_FILENAMES item code, it must follow the TPU$_FILENAME item 
code. 

• If you use either the TPU$_CHAIN item code or the TPU$JENDLIST code, it must be the last item 
code in the list. 

The following figure shows the general format of an item descriptor. For information about how to build 
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in item list, refer to the programmer's manual associated with the language you are using. Any reference to 
command line qualifiers refer to those command line qualifiers that you use with the EDIT/TPU command. 



Item code 



Buffer length 



Buffer address 



Return address 



ZK-4044-GE 



The return address in an item descriptor is usually 0. 



The following item codes are available: 



Item Code 


Description 


TPU$_OPTIONS 


Enables the command qualifiers. The bits in the bit mask specified by the buffer 
address field correspond to the various DECTPU command qualifiers. 


TPU$_JOURNALFILE 


Passes the string specified with the /JOURNAL qualifier. The buffer length 
field is the length of the string, and the buffer address field is the address of the 
string. This string is available with GET INFO 

(COMMAND_LINE,"JOURNAL_FILE M ). This string can be a null string. 


TPT QPTPTTfYMT7TT V 


Passes the string that is the name of the binary initialization file (section file) to 
be mapped in. The buffer length field is the length of the string, and the buffer 
address field is the address of the string. If the TPU$V_SECTION bit is set, this 
item code must be specified. 


TPU$_OUTPUTFILE 


Passes the string specified with the /OUTPUT qualifier. The buffer length field 
is the length of the string, and the buffer address field specifies the address of 
the string. This string is returned by the built-in procedure GET INFO 
(COMMANDLINE, "OUTPUT_FILE M ). The string can be a null string. 


TPU$_DISPLAYFILE 


Passes the string specified with the /DISPLAY qualifier. The buffer length field 
defines the length of the string, and the buffer address field defines the string 
address. The interface between the TPUSHR image and the display file image is 
not documented. Applications should only use this option with documented 
display files such as TPU$CCTSHR or TPU$MOTIFSHR. 


TPU$_COMMANDFILE 


Passes the string specified with the /COMMAND qualifier. The buffer length 
field is the length of the string, and the buffer address field is the address of the 
string. This string is returned by the built-in procedure GET INFO 
(COMMAND LINE, "COMMANDFILE"). The string can be a null string. 


TPU$_FILENAME 


Passes the string that is the name of the first input file specified on the 
command line. The buffer length field specifies the length of this string, and the 
buffer address field specifies its address. This string is returned by the built-in 
procedure GET INFO (COMMAND_LINE, "FIRST_FILE_NAME n ). This file 
name can be a null string. 




Passes a string that contains the name of an input file that follows the first input 
file on the command line. The buffer length field specifies the length of this 
string, and the buffer address field specifies its address. Each additional file 
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1 

TPU$_OTHER_FILENAMES 


specified on the command line requires its own TPU$_OTHER_FILENAMES 
item entry. These strings are returned by the GET INFO 
(COMMAND_LINE, M NEXT_FILE_NAME M ) built-in procedure in the order 
they appear in the item list. This item code must appear after the 
TPU$ FILENAME item in the item list. 


TPU$_FILEIO 


Passes the bound procedure value of a routine to be used for handling file 
operations. You can provide your own file I/O routine, or you can call 
TPU$FILEIO, the utility routine provided by DECTPU for handling file 
operations. The buffer address field specifies the address of a two-longword 
vector. The first longword of the vector contains the address of the routine. The 
second longword specifies the environment value that DECTPU loads into Rl 
before calling the routine. 


TPU$_CALLUSER 


Passes the bound procedure value of the user-written routine that the built-in 
procedure CALL_USER is to call. The buffer address field specifies the address 
of a two-longword vector. The first longword of the vector contains the address 
of the routine. The second longword specifies the environment value that 
DECTPU loads into Rl before calling the routine. 


TDT TC TXTTT tTTT C 

1 rU j>_1JN1 1 _r 1LH 


Passes the string specified with the /INITIALIZATION qualifier. The buffer 
length field is the length of the string, and the buffer address field is the address 
of the string. This string is returned by the built-in procedure GET INFO 
(COMMAND_LINE, n INIT_FILE"). 


TPU$_START_LINE 


Passes the starting line number for the edit. The buffer address field contains 
the first of the two integer values you specified as part of 
the /START POSITION command qualifier. The value is available using the 
built-in procedure GETINFO (COMMAND_LINE,"LINE n ). Usually an 
initialization procedure uses this information to set the starting position in the 
main editing buffer. The first line in the buffer is line 1 . 


TPU$_START_CHAR 


Passes the starting column position for the edit. The buffer address field 
contains the second of the two integer values you specified as part of 
the /START POSITION command qualifier. The value is available using the 
built-in procedure GET INFO (COMMAND LINE, "CHARACTER"). 
Usually an initialization procedure uses this information to set the starting 
position in the main editing buffer. The first column on a line to character 1 . 


TPU$_CHARACTERSET 


Passes the string specified with the /CHARACTER_SET qualifier. The buffer 
length field specifies the string length and the buffer address field specifies the 
string address. Valid strings are "DEC MCS" (the default value), 
n ISO_LATINl" 5 and "GENERAL". If the application tries to pass any other 
string, the routine signals an error and passes the default string (DEC_MCS). 


TPTTC WOPl^TT V! 
1 r U 4>_ W UKJvr YL^Cj 


Passes the string specified with the /WORK qualifier. The buffer length field 
specifies the string length and the buffer address specifies the string address. 
This string is available with GET INFO (COMMAND LINE, 
"WORK_FILE"). 


TPU$_CHAIN 


Passes the address of the next item list to the process specified by the buffer 
address field. 


TPU$ ENDLIST 


Signals the end of the item list. 


TPT DAD T7NJT W/TrwTET 


Passes the appropriate parent widget when invoking the DECwindows version 
of the editor. This routine is not specified by the application; DECTPU invokes 
its own application shell. The widget address is passed in the buffer address 
field. This item code is only valid when using the DECwindows interface. 




Passes the application context to use with the TPU$_PARENT_WIDGET. 



http://216.239 .37.104/search?q=cache:bbWuVlyAuyQJ:tigger.stcloudstate.edu/~tigger/openvms/72final/44... 8/26/03 



OpenVMS Utility Routines Manual 



Page 9 of 1 1 



TPU$_APPLICATION_CONTEXT 


DECTPU defaults to its own application context. The buffer address field 
specifies the application context address. This item code is only valid when 
using the DEC windows interface. 


1 r U3>_lJrJ,r AUL 1 orlLb 


Specifies which file DECTPU uses to initialize the X defaults database. The 
buffer length field specifies the string length and the buffer address field 
specifies the string address. This item code is only valid when using the 
DEC windows interface. 


TPU$_CTRL_C_ROUTINE 


Passes the bound procedure value of a routine to be used for handling Ctrl/C 
asynchronous system traps (ASTs). DECTPU calls the routine when a Ctrl/C 
AST occurs. If the routine returns a FALSE value, DECTPU assumes that the 
Ctrl/C has been handled. If the routine returns a TRUE value, DECTPU aborts 
any currently executing DECTPU procedure. The buffer address field specifies 
the address of a two-longword vector. The first longword of the vector contains 
the address of the routine. The second longword specifies the environment 
value that DECTPU loads into Rl before calling the routine. 


TPU$_DEBUGFILE 


Passes the string specified with the /DEBUG command qualifier. The buffer 
length field is the length of the string, and the buffer address field is the address 
of the string. 


TPU$_FILE_SEARCH 


Passes the bound procedure value of a routine to be used to replace the 
TPU$FILE_SEARCH routine which is called when the built-in procedure 
FILE SEARCH is called from TPU code. See the description of the 
TPU$FILE__SEARCH and the user routine FILE_SEARCH for more 
information. 


TPU$_FILE_PARSE 


Passes the bound procedure value of a routine to be used to replace the 
TPU$FILE_PARSE routine which is called when the built-in procedure 
FILE PARSE is called from TPU code. See the description of the 
TPUSFILE PARSE and the user routine FILE PARSE for more information. 



Table 8-1 lists the bits and corresponding masks enabled by the item code TPU$K_OPTIONS and shows how each bit 
affects TPU$INITIALIZE operation. Several bits in the TPU$_OPTIONS mask require additional item code entries in 
the item list. An example of this is TPU$M_COMMAND which requires a TPU$_COMMANDFILE entry in the item 
list. 



Table 8-1 Valid Masks for the TPU$K_OPTIONS Item Code 



Mask 1 


GETINFO 
Request String 2 


Description 


TPU$M_COMMAND 


COMMAND 


If DECTPU senses the presence of the 
TPU$_COMMANDFILE item, it tries to read, compile and 
execute the unbound TPU code. 


TPU$M_COMMAND_DFLTED 


Not applicable 


Specifies that DECTPU should use the default command file 
name of TPU$COMMAND.TPU when reading in the 
command file. No error is reported if the default command file 
is not found. TPU$INITIALIZE fails when the 
TPU$M_COMMAND_DFLTED bit is set to 0 and no file is 
specified in the item list. 


TPU$M_CREATE 


CREATE 


The behavior of DECTPU is not affected by this bit. Its 
interpretation is left to the application layered on DECTPU. 


TPU$M_DEBUG 


Not applicable 


If DECTPU senses the presence of the TPU$_DEBUGFILE 
item, it tries to read the file, and then proceeds to compile and 
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execute its contents as TPU statements. 


TPU$M_DEFAULTS 


Not applicable 


If DECTPU senses the presence of the 
TPU$_DEFAULTSFILE item, it uses the specified 
DECwindows X resource file to initialize the DECwindows X 
resource database. 


TPU$M_DISPLAY 


DISPLAY 


If DECTPU senses the presence of the TPU$_DISPLAYFILE 
item, it tries to image activate the specified image as its screen 
manager. When the bit is 0, DECTPU uses S YSSOUTPUT for 
display and only the READLINE built-in procedure may be 
used for input. 


TPU$M_INIT 


INITIALIZATION 


If DECTPU senses the presence of the TPU$_INIT_FILE 
item, it returns the specified string through the built-in 
procedure GET INFO (COMMAND LINE, 
M INITIALIZATION_FILE"). Processing of the initialization 
file is left to the application. 


TPU$M_JOURNAL 


JOURNAL 


If DECTPU senses the presence of the TPU$_JOURNALFILE 
item, it outputs the keystrokes entered during the editing 
session to the specified file. 

Note: Compaq recommends the use of buffer change 
journaling in new applications. 


TPU$M_MODIFY 


MODIFY 


The behavior of DECTPU is not affected by this bit. Its 
interpretation is left to the application layered on DECTPU. 


TPUSMNODEFAULTS 


Not applicable 


DECTPU initializes the DECwindows X resource database 
only with resource files that the DECwindows toolkit routine 
XtApplInitialize loads into the database. 


TPU$M_NOMODIFY 


NOMODIFY 


The behavior of DECTPU is not affected by this bit. Its 
interpretation is left to the application layered on DECTPU. 


TPU$M_OUTPUT 


OUTPUT 


The behavior of DECTPU is not affected by this bit. Its 
interpretation is left to the application layered on DECTPU. 


TPU$M READ 


READONLY 


The behavior of DECTPU is not affected by this bit. Its 
interpretation is left to the application layered on DECTPU. 


TPU$M_RECOVER 


RECOVER 


The behavior of DECTPU is not affected by this bit. Its 
interpretation is left to the application layered on DECTPU. 


1 r U 3>M_bbC 1 ION 


bbC I ION 


If DECTPU senses the presence of the TPU$_SECTIONFILE 
item, it tries to read the specified file as a binary initialization 
file. TPU$INITIALIZE fails if this bit is set to 1 and the 
TPU$__SECTIONFILE item is not present in the item list. 


TPU$M_SEC_LNM_MODE 


Not applicable 


If DECTPU senses the presence of the 
TPU$M_SEC_LNM_MODE item, it looks only at executive 
mode logical names when attempting to read in a section file. 


1 rUiM_WUKJv 


WUKJv 


If DECTPU senses the presence of the TPU$_WORKFILE 
item, it uses the specifed file for memory management. If no 
item list entry is present, and this bit is set to 1, a file is created 
in SYS$LOGIN:.TPU$WORK. 


TPU$M_WRITE 


WRITE 


The behavior of DECTPU is not affected by this bit. Its 
interpretation is left to the application layered on DECTPU. 



The prefix can be TPU$M_ or TPU$V_. TPU$M_ denotes a mask corresponding to the specific field in which the bit 
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"is set. TPU$V_ is a bit number. 

2 Most bits in the mask have a corresponding GETJNFO (COMMANDLINE) request string. 
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